Amiga Developer CD 2.1

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / CDTV / cdtvtools-20 / cdtv_device / cdtv.device.autodocs < prev next >

Wrap

Text File | 1992-02-06 | 42.4 KB | 1,551 lines

TABLE OF CONTENTS cdtv.device/--Background-- cdtv.device/CDTV_ADDCHANGEINT cdtv.device/CDTV_CHANGENUM cdtv.device/CDTV_CHANGESTATE cdtv.device/CDTV_FADE cdtv.device/CDTV_FRAMECALL cdtv.device/CDTV_FRAMECOUNT cdtv.device/CDTV_FRONTPANEL cdtv.device/CDTV_GENLOCK cdtv.device/CDTV_INFO cdtv.device/CDTV_ISROM cdtv.device/CDTV_MOTOR cdtv.device/CDTV_MUTE cdtv.device/CDTV_PAUSE cdtv.device/CDTV_PLAYLSN cdtv.device/CDTV_PLAYMSF cdtv.device/CDTV_PLAYSEGSLSN cdtv.device/CDTV_PLAYSEGSMSF cdtv.device/CDTV_PLAYTRACK cdtv.device/CDTV_POKEPLAYLSN cdtv.device/CDTV_POKEPLAYMSF cdtv.device/CDTV_POKESEGLSN cdtv.device/CDTV_POKESEGMSF cdtv.device/CDTV_QUICKSTATUS cdtv.device/CDTV_READ cdtv.device/CDTV_READXL cdtv.device/CDTV_REMCHANGEINT cdtv.device/CDTV_RESET cdtv.device/CDTV_SEEK cdtv.device/CDTV_STOPPLAY cdtv.device/CDTV_SUBQLSN cdtv.device/CDTV_SUBQMSF cdtv.device/CDTV_TOCLSN cdtv.device/CDTV_TOCMSF cdtv.device/CDTV_WRITE cdtv.device/CloseDevice cdtv.device/OpenDevice cdtv.device/--Background-- cdtv.device/--Background-- Background This document will describe some common terms and assumptions so that it need not be repeated everywhere. Common IORequest Fields Unless otherwise noted, certain fields in the IORequest or IOStdReq structure contain values common to all commands. The io_Device and io_Unit fields are filled by OpenDevice(). io_Flags can either be NULL or have the IOF_QUICK bit set. The io_Message structure should have the mn_ReplyPort field properly initialized to a valid reply port. Unused fields in the I/O request should be initialized to zero for future compatibility. Errors For all commands, if the io_Error field is non-zero, you must assume that the command failed, and that the requested action didn't happen or the returned data is invalid. The error codes are defined in <devices/cdtv.h>. Call-Back Environment For those commands that can call client routines, the CPU registers are initialized as follows (all other registers are undefined): Command: Registers: -------- ---------- CDTV_FRAMECALL A2: Pointer to I/O request used to invoke the command CDTV_PLAYSEGS{LSN,MSF} A2: Pointer to CDAudioSeg structure just started or completed CDTV_READXL A2: Pointer to CDXL node just completed D0,D1,A0,A1 may be trashed. All other registers must be preserved. Your code is called in interrupt mode on the supervisor stack (you may not take any kind of advantage of this fact). You are required to keep your code very brief. Your code must return via an RTS instruction. No return values are currently recognized, but put zero in D0 for future compatibility. Bugs Bugs are presented here for your convenience. However, Commodore reserves the right to fix any and all bugs. Do not rely on behaviors listed as bugs, as they are subject to change at any time. cdtv.device/CDTV_ADDCHANGEINT cdtv.device/CDTV_ADDCHANGEINT NAME CDTV_ADDCHANGEINT -- Add a disc-change interrupt to the driver. IO REQUEST io_Command CDTV_ADDCHANGEINT io_Data pointer to Exec Interrupt structure io_Length 0 io_Offset 0 RESULTS FUNCTION This command will install a software interrupt handler which will be invoked every time a disc is either removed or inserted into the drive. io_Data points to a properly initialized Exec Interupt structure. Once installed, you must be prepared to handle change interrupts immediately. Your handler will be called using standard Exec software interrupt conventions. From within the handler, the only commands in cdtv.device you may call are status commands that can use IOF_QUICK. These include CDTV_QUICKSTATUS, CDTV_REMCHANGEINT, CDTV_CHANGENUM, and CDTV_CHANGESTATE. The driver holds on to this command until explicitly released with CDTV_REMCHANGEINT using the same I/O request. Thus, you should use SendIO() with this command. EXAMPLE NOTES BUGS There is a bug in the hardware that will prevent you from seeing a disc change interrupt immediately if you happen to be in the middle of a data read when someone ejects the disc. You should use other indicators to detect this condition. SEE ALSO CDTV_REMCHANGEINT cdtv.device/CDTV_CHANGENUM cdtv.device/CDTV_CHANGENUM NAME CDTV_CHANGENUM -- Return the current value of the disc change counter. IO REQUEST io_Command CDTV_CHANGENUM io_Data NULL io_Length 0 io_Offset 0 RESULTS io_Actual the current value of the counter FUNCTION This command reports the current value of the disc change counter. The counter is incremented each time a disc is removed or inserted. EXAMPLE NOTES BUGS SEE ALSO CDTV_ADDCHANGEINT, CDTV_REMCHANGEINT cdtv.device/CDTV_CHANGESTATE cdtv.device/CDTV_CHANGESTATE NAME CDTV_CHANGESTATE -- Reports if a disc is present in the drive. IO REQUEST io_Command CDTV_CHANGESTATE io_Data NULL io_Length 0 io_Offset 0 RESULTS io_Actual current state of the drive (non-zero == drive empty; 0 == drive not empty (disc present)) FUNCTION This command will report whether or not a compact disc (not necessarily a CD-ROM) is present in the drive. EXAMPLE NOTES BUGS SEE ALSO CDTV_ISROM cdtv.device/CDTV_FADE cdtv.device/CDTV_FADE NAME CDTV_FADE -- Fade CD audio volume over time. IO REQUEST io_Command CDTV_FADE io_Data NULL io_Length fade duration, in frames io_Offset target volume level (0 - 0x7FFF) RESULTS FUNCTION This command will ramp the CD audio volume up or down from its current value to the value contained in io_Offset. The range is 0 (silence) to 0x7FFF (full volume). io_Length contains the duration of the fade. In seconds, this is: io_Length / 75 Note that this command returns before the fade has completed. Thus, once started, a fade cannot be aborted. You can, however, send a new CDTV_FADE command, which will immediately override any fade currently in progress. (An io_Length of zero is valid.) Fades happen in "Mode 1" as described in the CDTV_MUTE document. Fades continue to completion even if there is no CD audio operation in progress. It is recommended that you avoid invoking CDTV_MUTE while a fade is in progress, since they may interact in unexpected ways. EXAMPLE NOTES This command has no effect on Amiga audio volume. BUGS SEE ALSO CDTV_MUTE cdtv.device/CDTV_FRAMECALL cdtv.device/CDTV_FRAMECALL NAME CDTV_FRAMECALL -- Establish a CD frame callback function. IO REQUEST io_Command CDTV_FRAMECALL io_Data pointer to callback entry point io_Length 0 io_Offset number of CD frames to wait before invoking callback RESULTS FUNCTION This command will install a callback function which will be invoked when the requested number of CD frames has passed. Use the CDTV_INFO command to discover the prevailing frame rate. To be more precise, io_Offset is set to the number of frames to skip *between* each invocation of the call-back. For example, if io_Offset were set to 1, the driver would skip one frame, then call your code on the next, then skip one frame, then call your code on the next, etc. If io_Offset were set to 2, the driver would skip two frames, then call your code on the next, etc. If io_Offset were zero, your code would be called every frame (zero frames between calls). When installed, your code must be ready to handle the callback immediately. The callback will continue to be invoked until explicitly removed via AbortIO(). Thus, you should use SendIO() with this command. CALL-BACK ENVIRONMENT The CPU registers are initialized as follows (all other registers are undefined): A2: Pointer to I/O request used to invoke the command D0,D1,A0,A1 may be trashed. All other registers must be preserved. Your code is called in interrupt mode on the supervisor stack (you may not take any kind of advantage of this fact). You are required to keep your code very brief. Your code must return via an RTS instruction. No return values are currently recognized, but put zero in D0 for future compatibility. EXAMPLE NOTES BUGS SEE ALSO CDTV_FRAMECOUNT cdtv.device/CDTV_FRAMECOUNT cdtv.device/CDTV_FRAMECOUNT NAME CDTV_FRAMECOUNT -- Report the frame count since the disc was inserted. IO REQUEST io_Command CDTV_FRAMECOUNT io_Data NULL io_Length 0 io_Offset 0 RESULTS io_Actual number of frames since last insertion FUNCTION This command will return the number of CD frames that have passed since the disc was inserted into the drive. This can be used for synchronization purposes. Use the CDTV_INFO command to discover the prevailing frame rate. EXAMPLE NOTES The frame count will continue to accumulate whether the CD is spinning or not. BUGS SEE ALSO CDTV_FRAMECALL cdtv.device/CDTV_FRONTPANEL cdtv.device/CDTV_FRONTPANEL NAME CDTV_FRONTPANEL -- Enable/disable direct front panel control of the CD-ROM drive. IO REQUEST io_Command CDTV_FRONTPANEL io_Data NULL io_Length desired state (0 == disabled, 1 == enabled) io_Offset 0 RESULTS FUNCTION CDTV's front panel and IR remote controls can manipulate the audio capabilities of the CD-ROM drive directly, without Amiga intervention. This command enables/disables this capability. When the front panel is "enabled," it operates the drive directly, and no rawkey codes for the PLAY, STOP, FF, and REW keys are sent to the Amiga. When it is "disabled," this direct connection is broken, and the Amiga receives rawkey codes for those keys. EXAMPLE NOTES The rawkey codes for the IR buttons are currently: STOP 0x72 PLAY/PAUSE 0x73 FF 0x74 REW 0x75 BUGS There is a bug in the hardware whereby, if the Amiga sends any kind of command to the CD-ROM drive (including play commands), the front panel controls are disabled, and the drive will ignore all enable requests until the command is completed or aborted. SEE ALSO cdtv.device/CDTV_GENLOCK cdtv.device/CDTV_GENLOCK NAME CDTV_GENLOCK -- Control genlock output mode. IO REQUEST io_Command CDTV_GENLOCK io_Data NULL io_Length 0 io_Offset desired genlock mode RESULTS FUNCTION This command changes the operating mode of the genlock card. There are currently four modes: CDTV_GENLOCK_REMOTE permit IR remote to control genlock modes CDTV_GENLOCK_AMIGA display Amiga's video CDTV_GENLOCK_EXTERNAL display external video source CDTV_GENLOCK_MIXED display Amiga video overlayed on external video It is recommended that you return the genlock to CDTV_GENLOCK_REMOTE mode when your title is not using it. EXAMPLE NOTES There is no way to detect if a genlock card is installed in the system. However, you can detect if the system has booted in genlock mode (which strongly suggests the presence of a genlock card) by inspecting GfxBase.DisplayFlags to see if the GENLOC bit is set. BUGS SEE ALSO cdtv.device/CDTV_INFO cdtv.device/CDTV_INFO NAME CDTV_INFO -- Report information on CD-ROM drive/disc. IO REQUEST io_Command CDTV_INFO io_Data NULL io_Length 0 io_Offset info request code RESULTS io_Actual the data you requested FUNCTION This command is used to obtain information about the current configuration of the CD-ROM drive. The request code is placed in io_Offset. The requested data may be found in io_Actual. The available requests are: CDTV_INFO_BLOCK_SIZE report size of sectors, in bytes CDTV_INFO_FRAME_RATE report current CD frame rate, in frames per second EXAMPLE NOTES BUGS SEE ALSO cdtv.device/CDTV_ISROM cdtv.device/CDTV_ISROM NAME CDTV_ISROM -- Reports type of disc currently in CD-ROM drive. IO REQUEST io_Command CDTV_ISROM io_Data NULL io_Length 0 io_Offset 0 RESULTS io_Actual type of disc installed (0 == not a CD-ROM; non-zero == it's a CD-ROM) FUNCTION This command reports whether or not the disc currently in the drive is a CD-ROM (as opposed to an ordinary audio disc). EXAMPLE NOTES BUGS SEE ALSO CDTV_CHANGESTATE cdtv.device/CDTV_MOTOR cdtv.device/CDTV_MOTOR NAME CDTV_MOTOR -- Turn the CD-ROM drive's motor on/off. IO REQUEST io_Command CDTV_MOTOR io_Data NULL io_Length requested state of the motor (0 == off, 1 == on) io_Offset 0 RESULTS io_Actual previous state of motor FUNCTION This command causes the CD-ROM drive's motor to spin up or spin down. The desired state of the motor is placed in io_Length. The previous state of the motor is returned in io_Actual. If there is no disc in the drive, the motor stays off. Turning off the motor is discouraged, since it takes several seconds for the motor to spin back up. EXAMPLE NOTES If the drive remains idle for more than eight minutes, it turns the motor off. BUGS SEE ALSO cdtv.device/CDTV_MUTE cdtv.device/CDTV_MUTE NAME CDTV_MUTE -- Set CD audio volume. IO REQUEST io_Command CDTV_MUTE io_Data NULL io_Length mode of operation (0, 1, or 2) io_Offset desired volume level (0 - 0x7FFF) RESULTS io_Actual previous volume level FUNCTION This command sets the output volume for CD audio. Both left and right channels are affected. The io_Offset field contains the desired volume level. 0 is silence, 0x7FFF is full volume. The io_Length field specifies the mode of operation: 0: Do not set the volume. This is used to inspect the current volume level. 1: Set volume level to be used when a CD audio play operation is initiated. CD audio volume will be muted when the current play command is paused or aborted, or when a CDTV_STOPPLAY command is issued. 2: Set volume level immediately, regardless of current play state. This is normally used by system software. Its use is discouraged, since it is possible to play CD-ROM data by misusing this command. CD-ROM data sounds astonishingly bad. The previous volume level is returned in io_Actual. EXAMPLE NOTES This command has no effect on Amiga audio volume. BUGS SEE ALSO CDTV_FADE cdtv.device/CDTV_PAUSE cdtv.device/CDTV_PAUSE NAME CDTV_PAUSE -- Pause/un-pause the CD-ROM drive. IO REQUEST io_Command CDTV_PAUSE io_Data NULL io_Length 1 == pause drive; 0 == resume play io_Offset 0 RESULTS FUNCTION This command will pause and un-pause the laser on the drive during a CD audio play operation. The desired pause state is placed in io_Length. This command is typically used in CD audio applications. Audio output is suspended when the drive is paused. Audio output resumes when the drive is un-paused. EXAMPLE NOTES BUGS The drive does not latch the current pause state. That is, if you pause the drive, then issue one of the play commands, the drive will seek to the new play location and begin playing. If you wish the drive to remain paused in the new location, you must re-issue the pause command. If the drive is in the middle of a seek, it will ignore all attempts to pause it. SEE ALSO cdtv.device/CDTV_PLAYLSN cdtv.device/CDTV_PLAYLSN NAME CDTV_PLAYLSN -- Play CD audio from a specific location, LSN format. IO REQUEST io_Command CDTV_PLAYLSN io_Data NULL io_Length number of sectors to play io_Offset starting sector RESULTS FUNCTION This command causes the drive to start playing CD audio from the specified position, in LSN format. io_Offset specifies the starting position in LSN format. io_Length contains the number of sectors to play. The command will not return until the requested number of sectors has been played. The command may be aborted with AbortIO(). The audio will cease, but the laser will continue to track, and the drive light will remain on. Use the CDTV_STOPPLAY command after AbortIO() if you wish to halt this action. Please be sure that you're going to be playing CD audio data before issuing this command. CD-ROM data doesn't sound good. EXAMPLE /* Play one second of music starting at STARTLSN. */ ior->io_Command = CDTV_PLAYLSN; ior->io_Data = NULL; ior->io_Offset = STARTLSN; ior->io_Length = 75; DoIO (ior); NOTES BUGS SEE ALSO CDTV_PLAYMSF, CDTV_TOCLSN cdtv.device/CDTV_PLAYMSF cdtv.device/CDTV_PLAYMSF NAME CDTV_PLAYMSF -- Play CD audio from a specific location. IO REQUEST io_Command CDTV_PLAYMSF io_Data NULL io_Length stopping position, MSF format io_Offset starting position, MSF format RESULTS FUNCTION This command causes the drive to play CD audio from the location specified in MSF format. io_Offset specifies the starting location in MSF format. io_Length specifies the stopping location in MSF format (NOT the length, as in CDTV_PLAYLSN). The drive will play audio from the starting location up to, but not including, the stopping location. The command will not return until the requested segment has been played. The command may be aborted with AbortIO(). The audio will cease, but the laser will continue to track and the drive light will remain on. Use the CDTV_STOPPLAY command after AbortIO() to halt this action. EXAMPLE /* Play 10.333 seconds of music starting five minutes in. */ ior->io_Command = CDTV_PLAYMSF; ior->io_Data = NULL; ior->io_Offset = TOMSF (5, 0, 0); /* Start position */ ior->io_Length = TOMSF (5, 10, 25); /* End position */ DoIO (ior); NOTES You may care to use the TOMSF macro in <devices/cdtv.h> to create an MSF number. BUGS SEE ALSO CDTV_PLAYLSN, CDTV_TOCMSF, <devices/cdtv.h> cdtv.device/CDTV_PLAYSEGSLSN cdtv.device/CDTV_PLAYSEGSLSN NAME CDTV_PLAYSEGSLSN -- Play CD audio segments using a segment list, LSN format. IO REQUEST io_Command CDTV_PLAYSEGSLSN io_Data pointer to audio segment list header or list node. io_Length 0 io_Offset 0 RESULTS FUNCTION This command will play a sequence of audio "snippets" according to the information contained in the nodes of an audio segment list. The driver will play all the nodes in turn until it reaches the end of the list. The address of the list header or a CDAudioSeg node is placed into io_Data; the list is traversed from this point. The fields in the CDAudioSeg structure are as follows: Node Exec MinNode, for linking nodes Start Start position, LSN format Stop Number of logical sectors to play StartFunc Function to call when the audio segment starts playing StopFunc Function to call when the audio segment is completed This command will not return until all audio segments have been played. The command may be aborted using AbortIO(). CALL-BACK ENVIRONMENT If you use the StartFunc or StopFunc fields, your code will be called using the call-back environment described below. For StartFunc, your code will be called when the audio for the segment has actually commenced. For StopFunc, your code is called when the audio segment has completed. You may manipulate the segment list within both call-backs. The CPU registers are initialized as follows (all other registers are undefined): A2: Pointer to CDAudioSeg structure just started or completed D0,D1,A0,A1 may be trashed. All other registers must be preserved. Your code is called in interrupt mode on the supervisor stack (you may not take any kind of advantage of this fact). You are required to keep your code very brief. Your code must return via an RTS instruction. No return values are currently recognized, but put zero in D0 for future compatibility. EXAMPLE NOTES BUGS SEE ALSO CDTV_PLAYSEGSMSF, CDTV_POKESEGMSF cdtv.device/CDTV_PLAYSEGSMSF cdtv.device/CDTV_PLAYSEGSMSF CDTV_PLAYSEGSMSF -- Play CD audio segments using a segment list, MSF format. IO REQUEST io_Command CDTV_PLAYSEGSMSF io_Data pointer to audio segment list header or list node. io_Length 0 io_Offset 0 RESULTS FUNCTION This command is identical to CDTV_PLAYSEGSLSN, except that the Start and Stop fields in the CDAudioSeg structure are in MSF format. In addition, the CDAudioSeg.Stop field specifies the stopping location (not the length). See CDTV_PLAYSEGSLSN for more details. EXAMPLE NOTES BUGS SEE ALSO CDTV_PLAYSEGSLSN, CDTV_POKESEGLSN cdtv.device/CDTV_PLAYTRACK cdtv.device/CDTV_PLAYTRACK NAME CDTV_PLAYTRACK -- Play one or more tracks of CD audio. IO REQUEST io_Command CDTV_PLAYTRACK io_Data NULL io_Length stopping track, index io_Offset starting track, index RESULTS Music. FUNCTION This command causes the drive to play the specified audio track(s). The command will return when the audio has completed. io_Offset specifies the track number (starting from 1). It may optionally include an index in the upper 16 bits. io_Length specifies the track at which to stop (NOT the last track to be played). It may also optionally include a stopping index in the upper 16 bits. If io_Length is zero, the stopping position is taken to be the next track (no index). The command may be aborted using AbortIO(). The audio will cease, but the laser will continue to track, and the drive light will remain on. The CDTV_STOPPLAY command should be used after AbortIO() if you wish to halt this action. EXAMPLE /* Play three audio tracks starting at STARTTRACK */ ior->io_Command = CDTV_PLAYTRACK; ior->io_Data = NULL; ior->io_Offset = STARTTRACK; ior->io_Length = STARTTRACK + 3; DoIO (ior); NOTES BUGS SEE ALSO CDTV_PLAYLSN, CDTV_PLAYMSF cdtv.device/CDTV_POKEPLAYLSN cdtv.device/CDTV_POKEPLAYLSN NAME CDTV_POKEPLAYLSN -- Poke a play in progress, LSN format. IO REQUEST io_Command CDTV_POKEPLAYLSN io_Data NULL io_Length new play duration, in frames io_Offset new play location, LSN format RESULTS Seek to new location and commence audio from that point. FUNCTION This command will cause a play command in progress to seek to and commence play at a new location, specified in LSN format. The drive will start playing at the location contained in io_Offset. The new play length is contained in io_Length. This command eliminates the need to perform an AbortIO() and issue a new play command. It's useful for "fast-forward" type effects. A CDTV_PLAYLSN command must be in effect before issuing this command. EXAMPLE NOTES BUGS This command breaks a pause. SEE ALSO CDTV_PLAYLSN cdtv.device/CDTV_POKEPLAYMSF cdtv.device/CDTV_POKEPLAYMSF NAME CDTV_POKEPLAYMSF -- Poke a play in progress, MSF format. IO REQUEST io_Command CDTV_POKEPLAYMSF io_Data NULL io_Length new stop location, MSF format io_Offset new play location, MSF format RESULTS Seek to new location and commence audio from that point. FUNCTION This command will cause a play command in progress to seek to and commence play at a new location, specified in MSF format. The drive will start playing at the location contained in io_Offset. The new stopping location is contained in io_Length. This command eliminates the need to perform an AbortIO() and issue a new play command. It's useful for "fast-forward" type effects. A CDTV_PLAYMSF command must be in effect before issuing this command. EXAMPLE NOTES BUGS This command breaks a pause. SEE ALSO CDTV_PLAYMSF cdtv.device/CDTV_POKESEGLSN cdtv.device/CDTV_POKESEGLSN NAME CDTV_POKESEGLSN -- Jump to an entry in an audio segment list, LSN format. IO REQUEST io_Command CDTV_POKESEGLSN io_Data pointer to CDAudioSeg node io_Length 0 io_Offset new start position, LSN format RESULTS FUNCTION This command will cause the device driver to jump to the CDAudioSeg node pointed to by io_Data. The fields in the CDAudioSeg node are in LSN format. The drive will seek and immediately begin playing at the position specified by the io_Offset field in the I/O request. The length is taken from the Stop field in the specified node. The device driver will then continue playing the entries in the segment list from this point. A CDTV_PLAYSEGSLSN command must be in effect before invoking this command. EXAMPLE NOTES The target node can be a member of a completely different list. BUGS SEE ALSO CDTV_POKESEGMSF cdtv.device/CDTV_POKESEGMSF cdtv.device/CDTV_POKESEGMSF NAME CDTV_POKESEGMSF -- Jump to an entry in an audio segment list, MSF format. IO REQUEST io_Command CDTV_POKESEGMSF io_Data pointer to CDAudioSeg node io_Length 0 io_Offset new start position, MSF format RESULTS FUNCTION This command will cause the device driver to jump to the CDAudioSeg node pointed to by io_Data. The fields in the CDAudioSeg node are in MSF format. The drive will seek and immediately begin playing at the position specified by the io_Offset field in the I/O request. The stopping position is taken from the Stop field in the specified node. The device driver will then continue playing the entries in the segment list from this point. A CDTV_PLAYSEGSMSF command must be in effect before invoking this command. EXAMPLE NOTES The target node can be a member of a completely different list. BUGS SEE ALSO CDTV_POKESEGLSN cdtv.device/CDTV_QUICKSTATUS cdtv.device/CDTV_QUICKSTATUS NAME CDTV_QUICKSTATUS -- Return current status of the CD-ROM drive. IO REQUEST io_Command CDTV_QUICKSTATUS io_Data NULL io_Length 0 io_Offset 0 RESULTS io_Actual current status of drive, as a set of bits: QSF_READY drive is ready QSF_AUDIO CD digital audio is playing QSF_DONE last hardware command completed QSF_ERROR error in last hardware command QSF_SPIN disc is spinning QSF_DISK disc is present in drive QSF_INFERR positioning error FUNCTION This command reports the current status of the CD-ROM drive. This command is super-fast, and is always synchronous. This command may safely be used from within interrupts. The status is returned in io_Actual. If no status is available, io_Actual will contain zero. The bits QSF_READY, QSF_DONE, QSF_ERROR, and QSF_INFERR should not be relied upon to relay any kind of useful information, and should be ignored. EXAMPLE NOTES This command may also be called directly as a function to cut overhead in time critical code (A6 must be set to cdtv device base and A4 set to point to the I/O request block). BUGS SEE ALSO cdtv.device/CDTV_READ cdtv.device/CDTV_READ NAME CDTV_READ -- Read bytes off a CD-ROM IO REQUEST io_Command CDTV_READ io_Data pointer to buffer to receive data (word-aligned) io_Length number of bytes to read (must be even) io_Offset offset in bytes from beginning of disc to begin reading (must be even) RESULTS io_Actual actual number of bytes read. This may differ from the amount requested. FUNCTION This command reads bytes from CD-ROM sectors. CD-ROM transfers are word-oriented, so the destination buffer must be word-aligned and an even number of bytes. The starting position on the disc must also be an even number. Unlike other Amiga block devices, the transfer need not be sector aligned. Sectors are DMA'd into the system in 2K bursts. During this time, bus cycles are stolen from the CPU to move the data. The bursts take 1.3 milliseconds, and occur at the CD frame rate. EXAMPLE NOTES The io_Offset parameter is not restricted to any particular track; it will read from any position on the disc that contains CD-ROM data. io_Offset's "zero point" is the first byte of the first valid frame on the disc. This is usually MSF 00:02.00 (LSN 0), but the disc's table of contents will tell you definitely where this is. CD-ROM mode 2, form 2 sector sizes are not supported by this command. CDTV_READXL must be used for sectors of this type. The time it takes to burst a sector into memory may change in the future. The hardware prohibits all attempts by the Amiga to read CD audio data. BUGS There is a bug in the hardware such that the last few bytes in a given request may not be transferred. The current workaround is to pad your buffers and your disk data by the value READ_PAD_BYTES, and to request READ_PAD_BYTES more bytes than you would otherwise. Thus, any missing bytes are part of the padding, and ignored. READ_PAD_BYTES is defined in <devices/cdtv.h>. SEE ALSO CDTV_READXL cdtv.device/CDTV_READXL cdtv.device/CDTV_READXL NAME CDTV_READXL -- Read from CD-ROM into memory via transfer list. IO REQUEST io_Command CDTV_READXL io_Data pointer to transfer list header or list node. io_Length number of sectors to read (-1 == forever) io_Offset starting sector, from beginning of disc RESULTS Truly amazing. FUNCTION Our Secret Weapon. (Patent Pending) This command starts reading data off the disc at the specified location and deposits it into memory according to the nodes in the transfer list. The total number of sectors to transfer is placed in io_Length. The address of the transfer list header, or one of its nodes, is placed in io_Data. Note that io_Offset and io_Length are specified in sectors rather than bytes. An io_Length of zero is valid (this has the effect of a seek). An io_Length of -1 will read sectors forever. The fields in the CDXL node structure are: Node Exec list MinNode Buffer address to deposit CD-ROM data Length number of bytes to transfer DoneFunc function to call when transfer is complete Actual filled in with number of bytes actually read The philosophy here is that you set up the buffers you want filled, create CDXL nodes describing the locations and sizes of these buffers, assemble into a list, and invoke the command. The driver then fills the buffers in a single pass. If you fill in the DoneFunc field with a pointer to a call-back function, your routine will be called when the transfer for the node is complete. Your code will be called before the driver proceeds to the next node. You may manipulate the list from within the call-back. This command completes when the specified number of sectors have been read, or the end of the transfer list is reached. The command can also be aborted via AbortIO(). CALL-BACK ENVIRONMENT The CPU registers are initialized as follows (all other registers are undefined): A2: Pointer to CDXL node just completed D0,D1,A0,A1 may be trashed. All other registers must be preserved. Your code is called in interrupt mode on the supervisor stack (you may not take any kind of advantage of this fact). You are required to keep your code very brief. Your code must return via an RTS instruction. No return values are currently recognized, but put zero in D0 for future compatibility. EXAMPLE NOTES Internally, an interrupt is generated as each node is completed. Thus, if you set up a list with a lot of small buffers (less than 2K each or so), the machine will be saturated with interrupts and will be unable to keep up, and the transfer will abort with an error. Try to avoid this condition. (The occasional small buffer is okay.) Remember, io_Offset and io_Length are in SECTORS, not bytes. BUGS The bug described in CDTV_READ (missing bytes at the end) applies here, too, with the extra caveat that *all* buffers and request lengths described in the list must be padded by READ_PAD_BYTES. SEE ALSO CDTV_READ, CDTV_SEEK cdtv.device/CDTV_REMCHANGEINT cdtv.device/CDTV_REMCHANGEINT NAME CDTV_REMCHANGEINT -- Remove a disc-change interrupt. IO REQUEST The *same* IORequest used to invoke the CDTV_ADDCHANGEINT command: io_Command CDTV_REMCHANGEINT io_Data pointer to Exec Interrupt structure io_Length 0 io_Offset 0 RESULTS The specified change interrupt is removed, and the CDTV_ADDCHANGEINT command is returned. FUNCTION This command removes a disc-change interrupt handler previously installed by CDTV_ADDCHANGEINT. This command must be invoked using the same I/O request used to invoke the CDTV_ADDCHANGEINT command. EXAMPLE NOTES BUGS SEE ALSO CDTV_ADDCHANGEINT cdtv.device/CDTV_RESET cdtv.device/CDTV_RESET NAME CDTV_RESET -- Reset drive hardware. IO REQUEST io_Command CDTV_RESET io_Data NULL io_Length 0 io_Offset 0 RESULTS FUNCTION This command issues a reset to the drive, as if the RESET line had been asserted. The drive then performs its internal initialization sequence before it becomes available. This can take several seconds. EXAMPLE NOTES BUGS SEE ALSO cdtv.device/CDTV_SEEK cdtv.device/CDTV_SEEK NAME CDTV_SEEK -- Seek to a position on the disc. IO REQUEST io_Command CDTV_SEEK io_Data NULL io_Length 0 io_Offset number of bytes from beginning of disc RESULTS FUNCTION This command will cause the laser to seek as close as possible to the requested location. EXAMPLE NOTES io_Offset's "zero point" is the first byte of the first valid frame on the disc. This is usually MSF 00:02.00 (LSN 0), but the disc's table of contents will tell you definitely where this is. This command will span tracks. However, the target location must contain CD-ROM data. BUGS SEE ALSO CDTV_READ, CDTV_READXL cdtv.device/CDTV_STOPPLAY cdtv.device/CDTV_STOPPLAY NAME CDTV_STOPPLAY -- Stop CD audio play. IO REQUEST io_Command CDTV_STOPPLAY io_Data NULL io_Length 0 io_Offset 0 RESULTS Silence. FUNCTION This command will halt a play command. The laser will seek to zero, and the drive activity light will go out. Any running audio commands (CDTV_PLAY#?) must be aborted via AbortIO() before this command is used. EXAMPLE NOTES BUGS SEE ALSO AbortIO() cdtv.device/CDTV_SUBQLSN cdtv.device/CDTV_SUBQLSN NAME CDTV_SUBQLSN -- Report current disc position and status, LSN format. IO REQUEST io_Command CDTV_SUBQLSN io_Data pointer to CDSubQ structure io_Length 0 io_Offset 0 RESULTS FUNCTION This command reports the current SubQ channel information. io_Data points to a CDSubQ structure to be filled by the driver. The fields in the CDSubQ structure are: Status current drive/disc status (see below) AddrCtrl SubQ bits (see below) Track current track Index current index within track DiskPosition current position relative to start of disc, LSN fmt. TrackPosition current position relative to start of current track, LSN format ValidUPC indicates detection of a UPC/ISRC code (see below) STATUS The Status field is numeric, and can have the following values: SQSTAT_NOTVALID this SubQ report is not valid SQSTAT_PLAYING drive is currently playing CD audio SQSTAT_PAUSED drive is currently paused SQSTAT_DONE most recent play command completed successfully SQSTAT_ERROR most recent play command generated an error SQSTAT_NOSTAT no status available; this report is invalid This field must be sanity-checked. ADDRCTRL The lower four bits of the AddrCtrl field are status bits. Their meanings are: ADRCTLF_PREEMPH this track has pre-emphasis ADRCTLF_COPY this track may be digitally copied (we have never observed this bit to be set :-). In no case is CD digital audio data readable by the Amiga) ADRCTLF_DATA this track is CD-ROM data (as opposed to audio) ADRCTLF_4CHAN this track contains 4-channel sound The upper four bits of the AddrCtrl field are numeric. The possible values are: ADRCTL_NOMODE no mode info available; this report is invalid ADRCTL_POSITION this report contains position information ADRCTL_MEDIACAT this report contains a UPC code ADRCTL_ISRC this report contains an ISRC number This entire field must be sanity-checked. VALIDUPC The ValidUPC field contains status bits. They are: SQUPCB_VALID UPC/ISRC code detected SQUPCB_ISRC set == ISRC detected; clear == UPC detected EXAMPLE NOTES It is STRONGLY recommended that you perform massive sanity checks on the SubQ information before assuming it is correct. Check that the Status and AddrCtrl fields both indicate that you have received valid data, and that the DiskPosition field represents a valid position. BUGS Even after passing massive sanity checks, the drive may still hand you bogus SubQ data. Sigh... The current drive will go severely south if you feed SubQ requests too rapidly. Try to keep it down below 20 requests per second. The current drive does not report UPC or ISRC codes correctly. SEE ALSO CDTV_SUBQMSF cdtv.device/CDTV_SUBQMSF cdtv.device/CDTV_SUBQMSF NAME CDTV_SUBQMSF -- Report current disc position and status, MSF format. IO REQUEST io_Command CDTV_SUBQMSF io_Data pointer to CDSubQ structure io_Length 0 io_Offset 0 RESULTS FUNCTION This command reports the current SubQ channel information. This command is identical to CDTV_SUBQLSN, except that the position information in the CDSubQ structure is expressed in MSF format. For more details, see CDTV_SUBQLSN. SEE ALSO CDTV_SUBQLSN cdtv.device/CDTV_TOCLSN cdtv.device/CDTV_TOCLSN NAME CDTV_TOCLSN -- Report disc's table of contents, LSN format IO REQUEST io_Command CDTV_TOCLSN io_Data pointer to array of CDTOC structures io_Length number of CDTOC entries to be fetched io_Offset track number at which to start (0 == volume summary) RESULTS io_Actual highest track number written to array (does not include volume summary, if requested) FUNCTION This command returns the table of contents of the disc currently in the drive. The data is expressed in LSN format. The io_Data field points to an array of CDTOC structures to receive the TOC data. The io_Length field specifies the total number of entries to be fetched. The CDTOC array must be at least this many elements in size. The io_Offset field specifies the track number at which to start gathering TOC data. If it is set to zero, the first TOC entry will contain a volume summary (see below). It may take the drive up to four seconds to read the TOC upon disc insertion. If the TOC is not yet available, or there is no disc in the drive, an error will be returned. CDTOC For ordinary tracks, the CDTOC entries will contain the following: AddrCtrl SubQ flags describing track type Track track number LastTrack -na- Position location of the start of the track, LSN format If a volume summary is requested, then the first entry in the array is interpreted differently. It will describe the entire disc, and will contain the following: AddrCtrl -na- Track first track number LastTrack last track number Position location of the lead-out (end of disc), LSN format EXAMPLE /* Read Table Of Contents with volume summary */ struct CDTOC tocarray[100]; ior->io_Command = CDTV_TOCLSN; ior->io_Offset = 0; /* Gimme summary */ ior->io_Length = 100; /* Max 99 tracks + summary */ ior->io_Data = tocarray; DoIO (ior); if (!ior->io_Error) { firsttrack = tocarray[0].Track; lasttrack = tocarray[0].LastTrack; /* * Compute total length of disc. This is the location of * the lead-out, minus the start of the first track (which * is not always zero). */ totalsectors = tocarray[0].Position.LSN - tocarray[1].Position.LSN; } NOTES BUGS SEE ALSO CDTV_TOCMSF cdtv.device/CDTV_TOCMSF cdtv.device/CDTV_TOCMSF NAME CDTV_TOCMSF -- Report disc's table of contents, MSF format IO REQUEST io_Command CDTV_TOCMSF io_Data pointer to array of CDTOC structures io_Length number of CDTOC entries to be fetched io_Offset track number at which to start (0 == volume summary) RESULTS io_Actual highest track number written to array (does not include volume summary, if requested) FUNCTION This command returns the table of contents of the disc currently in the drive. This command is identical to CDTV_TOCLSN, except that the position data in the CDTOC structures is expressed in MSF format. For more details, see CDTV_TOCLSN. EXAMPLE NOTES BUGS SEE ALSO CDTV_TOCLSN cdtv.device/CDTV_WRITE cdtv.device/CDTV_WRITE NAME CDTV_WRITE -- Writes data to a CD-ROM. FUNCTION This command writes data to the CD-ROM at the current seek position. Note that reading the data back might be difficult... RESULTS The line voltage is switched through to the laser, causing it to go PHWATTTT!!! and burn enormous holes in the CD-ROM, through the top of the case, and through whatever stereo component happens to be on top of the CDTV. We recommend invoking this command if you detect that a CD-I or MPC player has been placed on top of the CDTV. Invoking this command voids the warranty. SERIOUSLY This command always returns CDERR_WRITEPROT (disc is write- protected). SEE ALSO CDTV_READ (much more useful) cdtv.device/CloseDevice cdtv.device/CloseDevice NAME CloseDevice -- Terminate access to cdtv.device. SYNOPSIS CloseDevice (ior); A1 struct IOStdReq *ior; FUNCTION This function terminates access to the cdtv.device. 'ior' points to a IOStdReq structure that was initialized by OpenDevice(). After calling CloseDevice(), 'ior' may no longer be used to send commands to cdtv.device. INPUTS ior - pointer to an IOStdReq structure RESULT The io_Device and io_Unit fields of the IOStdReq structure are invalidated. NOTES BUGS SEE ALSO OpenDevice() cdtv.device/OpenDevice cdtv.device/OpenDevice NAME OpenDevice -- Open the cdtv.device for use. SYNOPSIS error = OpenDevice ("cdtv.device", unit, ior, flags); D0 A0 D0 A1 D1 LONG error; LONG unit; struct IOStdReq *ior; LONG flags; FUNCTION This call opens the cdtv.device and makes it available for use. The 'unit' and 'flags' parameters to OpenDevice() should be set to zero for future compatibility. INPUTS unit - 0 ior - pointer to IOStdReq structure flags - 0 RESULT error - non-zero if error, zero if opened successfully The io_Device and io_Unit fields of the IOStdReq structure are initialized. NOTES io_Device and io_Unit may be safely cloned to create multiple I/O requests. BUGS SEE ALSO CloseDevice()